---
title: "Learner Bot"
type: entity
created: 2026-04-18
updated: 2026-04-18
sources: ["raw/notes/LEARNER_BOT_SPEC.md", "raw/notes/memory.md", "raw/articles/03-architecture.md"]
tags: [service, learner-bot, ai-agent, nightly-cycle, per-child-ai]
---

# Learner Bot

The Learner Bot is [[Pickatale]]'s per-child AI agent. It runs at port 3120 and is the intelligence layer that transforms raw reading telemetry into actionable insights for teachers and parents. Every student on the platform has a persistent AI memory managed by the Learner Bot — a living model of their reading level, vocabulary gaps, learning patterns, and curriculum progress.

## Service Details

| Attribute | Value |
|---|---|
| Port | 3120 |
| Code location | `/home/ubuntu/learner-bot/` |
| Database | `learner_bot` on shared MySQL |
| Internal auth | `X-Internal-Key: <INTERNAL_KEY> (stored in secure env — see .env)` |
| Nightly run cron | `04:00 UTC` daily |
| Retention cron | `03:00 UTC` daily (telemetry purge) |
| Endpoints | 20 verified endpoints |
| Status | ✅ Verified: 8 test learners processed, zero errors (2026-04-17) |

## Memory Model

The Learner Bot maintains five distinct memory types per child, forming a rich per-child RAG (Retrieval-Augmented Generation) store:

| Memory Type | Description |
|---|---|
| `assessment_result` | Placement test scores, quiz results, WCPM measurements |
| `curriculum_state` | Which curriculum objectives have been introduced, practiced, or mastered |
| `vocabularyGaps` | Words the student taps frequently — aggregated from [[Telemetry Service]] vocab-tap feeds |
| `reading_pattern` | Pace, time-of-day, session length, genre preferences |
| `engagement_signal` | Streak data, abandonment patterns, motivation indicators |

These five types are stored as structured JSON blobs keyed by `learner_id` in the `learner_bot` database. The nightly AI run reads all five before generating any recommendation or report.

## Inbound Data Sources

The Learner Bot is a consumer — it does not generate events. It receives data from:

1. **[[Telemetry Service]]** — two parallel POSTs after every `session_end`:
   - `POST /ingest/vocab-taps` — word-tapped events for the session
   - `POST /ingest/session-summary` — FK level, WCPM, pages read, duration
2. **[[Teacher Portal]]** — quiz scores and manual teacher notes via internal API
3. **Placement tests** — full placement result submitted on first student login

## Nightly Run Cycle

The primary AI computation happens in the nightly cron at **04:00 UTC**. For each active learner:

```mermaid
flowchart TD
    A[Load learner memory — 5 types] --> B[Pull recent telemetry events]
    B --> C[GPT-4o: analyze patterns, detect gaps]
    C --> D[Update memory store — all 5 types]
    D --> E[Generate attention flags for Teacher Portal]
    E --> F[Generate teacher report digest]
    F --> G[Generate parent digest — if parent linked]
    G --> H[Update Adaptive Engine FK level recommendation]
```

The nightly cycle is designed to be **idempotent**: re-running it for the same date produces the same output without creating duplicate records.

**⚠️ Non-Negotiable (Sig):** The nightly run must complete before teachers arrive in the morning (assumed 07:00 local school time). It is scheduled at 04:00 UTC to provide a 3-hour buffer globally. If processing takes longer than 90 minutes, an alert is triggered.

## Telemetry Retention Cron

A separate cron runs at **03:00 UTC** (one hour before the nightly AI run) to purge raw telemetry events older than 7 days. The Learner Bot absorbs the signal from raw events into its memory store before they are deleted. This ensures the 7-day retention policy in the [[Telemetry Service]] does not cause data loss at the AI layer.

## Outputs

The Learner Bot produces three categories of output:

### Teacher Portal Feeds
- **Attention list flags** — which students need intervention and why
- **Learner profiles** — enriched per-student views with AI reasoning
- **Curriculum objective progress** — mapped to the territory's curriculum

### Parent Digests
- Weekly email summaries (if parent linked and opted in)
- Highlights: books read, words learned, milestones reached

### Adaptive Engine Signal
- FK level recommendation for each learner, consumed by the [[Adaptive Engine]] for book selection

## API Surface

The Learner Bot exposes **20 verified endpoints**, broadly grouped:

| Group | Examples |
|---|---|
| Ingest | `POST /ingest/vocab-taps`, `POST /ingest/session-summary`, `POST /ingest/assessment` |
| Query | `GET /learner/:id/memory`, `GET /learner/:id/attention-flags`, `GET /learner/:id/report` |
| Admin | `POST /run/nightly`, `GET /run/status`, `DELETE /learner/:id/memory` |

All endpoints require the `X-Internal-Key` header. None are publicly accessible — they are internal service-to-service APIs only, never exposed through the Caddy reverse proxy.

## Verification Record

As of **2026-04-17**, the Learner Bot was verified end-to-end against 8 test learners with zero processing errors across all 20 endpoints. All five memory types were written and read back correctly. Nightly run simulation completed in under 4 minutes for the 8-learner test set.

## Related Pages

- [[entities/Telemetry Service]] — primary data source (session events, vocab taps)
- [[entities/Teacher Portal]] — consumes attention flags and learner profiles
- [[entities/Adaptive Engine]] — reads FK level recommendations from Learner Bot
- [[concepts/learner-bot/index]] — concept overview of the Learner Bot subsystem
- [[concepts/learner-bot/Memory Model]] — deep dive into the 5 memory types
- [[concepts/learner-bot/Nightly Cycle]] — detailed walkthrough of the nightly AI run
- [[concepts/learner-bot/Bot Endpoints]] — full endpoint reference